RtWaitForSingleObjectEx
RtWaitForSingleObjectEx allows a thread to wait on an object to be signaled with high granularity of time-out interval.
Syntax
DWORD RtWaitForSingleObjectEx( HANDLE hHandle, PULARGE_INTEGER lpWaitTimeOut );
Parameters
hHandle
The object identifier. See the list of the object types whose handles can be specified in the Remarks section.
lpWaitTimeOut
The pointer to time-out interval in 100-nanosecond units. The function returns if the interval elapses, even if the object's state is non-signaled. If lpWaitTimeOut is NULL, the function returns WAIT_FAILED with last error ERROR_INVALID_PARAMETER. If lpWaitTimeOut ->QuadPart is zero, the function tests the object's state and returns immediately. If both lpWaitTimeOut ->LowPart and lpWaitTimeOut ->HighPart are INFINITE, the function's time-out interval never elapses. Otherwise, lpWaitTimeOut ->QuadPart modules down to the multiple of RTX64 HAL Clock period. If the value becomes zero after module down, the time-out interval elapses to the next tick.
Return Value
The event that caused the function to return, if the function succeeds, WAIT_FAILED if the function fails
To get extended error information, call GetLastError.
Possible return values on success are:
Value | Description |
---|---|
WAIT_ABANDONED |
The specified object is a mutex object that was not released by the thread that owned the mutex object before the owning thread terminated. Ownership of the mutex object is granted to the calling thread, and the mutex is set to non-signaled. |
WAIT_OBJECT_0 |
The state of the specified object is signaled. |
WAIT_TIMEOUT |
The time-out interval elapsed, and the object's state is non-signaled. |
Remarks
RtWaitForSingleObjectEx checks the current state of the specified object. If the object's state is non-signaled, the calling thread enters an efficient wait state. The thread consumes very little processor time while waiting for the object state to become signaled or the time-out interval to elapse.
The function returns when one of these events occurs:
- The specified object is in the signaled state.
- The time-out interval elapses.
Before returning, a wait function modifies the state of some types of synchronization objects. Modification occurs only for the object or objects whose signaled state caused the function to return. For example, the count of a semaphore object is decreased by one.
RtWaitForSingleObjectEx can wait for the following objects:
- Semaphore
RtCreateSemaphore or RtOpenSemaphore returns the handle. A semaphore object maintains a count between zero and some maximum value. Its state is signaled when its count is greater than zero and non-signaled when its count is zero. If the current state is signaled, the wait function decreases the count by one. - Mutex
RtCreateMutex and RtOpenMutex return handles to the mutex object which becomes signaled when the mutex is unowned. - Event
The RtCreateEvent or RtOpenEvent function returns the handle that can be waited on. An event object's state is set explicitly to signaled by the RtSetEvent or RtPulseEvent function. A manual-reset event object's state must be reset explicitly to nonsignaled by the RtResetEvent function. For an auto-reset event object, the wait function resets the object's state to nonsignaled before returning. - Thread
The function CreateThread returns a handle. This handle is value for the life of the thread so it can be waited on to determine when the thread is completed.. - Process
The function RtCreateProcess and RtOpenProcess return the process handle, this handle is valid for the life of the process so it can be waited on to determine when the processor has exited.
NOTE: RtWaitForSingleObjectEx can only be called from a RTSS process or RTDLL.
Requirements
Minimum Supported Version | RTX64 2013 with Service Pack 1 |
Header | RtssApi.h |
Library | Rtx_Rtss.lib |
See Also: